@Part(Vector, Root = "CLM.MSS")
@Comment{Chapter of Common Lisp Manual.  (c) 1981 Carnegie-Mellon University⎇


@Chapter[Vectors]

A vector is a simple one-dimensional sequence of objects.
Each vector has a fixed length @i[n] peculiar to that vector;
the elements of the vector are numbered from zero to @i[n]-1.

Vectors differ from lists in that
it takes constant time to make a list longer (using
the function @Funref[cons]) and linear time to access
an arbitrary element (using the function @Funref[nth], for example),
while for a vector this is reversed: it takes linear time
to extend a vector, but accessing an element takes constant time.
Hence the use of lists or vectors for a particular application should
be dictated primarily by efficiency considerations.

Vectors are divided into various subtypes, depending on what
class of @xlisp objects they are capable of containing.
A vector capable of containing objects of type @i[type]
is said to be of type @f[(vector @i[type])].
A request (to the function @f[make-vector]) to construct a vector
of type @f[(vector @i[type1])] may or may not succeed, however;
it may produce such a vector, or it may produce a vector whose actual
type is @f[(vector @i[type2])], where @i[type1] is a subtype of @i[type2].
Each implementation will respond to such a request by using the
most specific type @i[type2] for which it provides vectors of that
concrete type.

All implementations of @clisp must provide three concrete vector
types: general vectors, whose type is @f[(vector t)], and which
can contain any @xlisp object; bit-vectors, whose type is
@f[(vector (mod 2))], and which can contain bits
(the integers @f[0] and @f[1]);
and strings, whose type is @f[(vector string-char)],
and which can contain a certain subset of the character data type.
Implementations may choose to provide other specialized concrete vector types
as well; a common choice is vectors of type
@Lisp
(vector (mod @i[n]))  @r[for @i[n] = 2@+[2@+[@i[j]]] for integral @i[j]]
@Endlisp

@Section[Creating Vectors]

@Defun[Fun {make-vector⎇, Args {@i[length] @optional @i[type] @i[initial-value]⎇]
A new vector is created and returned.  It will contain @i[length]
elements; @i[length] must be a non-negative integer.
It will be of type @f[(vector @i[ctype])], where @i[ctype] is the
most specific type for which the implementation provides a concrete
representation of vectors of that type, such that @i[type] is a subtype
of @i[ctype].  The @i[type] defaults to @true.  Each element
of the vector will be @i[initial-value], which must be of type @i[type];
but if the @i[initial-value] is not provided, then the initial contents
of the vector are implementation-dependent (but each element must
nevertheless be of type @i[type]).
@Enddefun

@Defun[Fun {make-bit-vector⎇, Args {@i[length] @optional @i[initial-value]⎇]
This is precisely equiva;
@Enddefun

@Section[Functions on General Vectors (Vectors of @xlisp Objects)]

The functions in this section are equivalent in operation to the
corresponding generic sequence functions, but require sequence
arguments to be vectors of type @f[(vector t)].

@Defun[Fun {vref⎇, Args {@i[vector] @i[index]⎇]
The element of the @i[vector] specified by the integer @i[index]
is returned.  The @i[index] must be non-negative and less than
the length of the vector.  See @Funref[elt].
@Enddefun

@Defun[Fun {vset⎇, Args {@i[vector] @i[index] @i[newvalue]⎇]
The @xlisp object @i[newvalue] is stored into the component of
the @i[vector] specified by the integer @i[index].
The @i[index] must be non-negative and less than
the length of the vector.  The @i[newvalue] must be suitable for
storing into the @i[vector] if the @i[vector] is of a specialized type.
See @Funref[setelt].
@Enddefun

@Section[Functions on Bit-Vectors]

@Defun[Fun {bit⎇, Args {@i[bit-vector] @i[index]⎇]
The element of the @i[bit-vector] specified by the integer @i[index]
is returned.  The @i[index] must be non-negative and less than
the length of the vector.  The result will always be @f[0] or @f[1].
See @Funref[elt].
@Enddefun

@Defun[Fun {rplacbit⎇, Args {@i[bit-vector] @i[index] @i[newbit]⎇]
The @i[newbit] is stored into the component of
the @i[bit-vector] specified by the integer @i[index].
The @i[index] must be non-negative and less than
the length of the vector.  The @i[newvalue] must be @f[0] or @f[1].
See @Funref[setelt].
@Enddefun

@Defun[Fun {bit-and⎇, Args {@rest @i[bit-vectors]⎇]
@Defun1[Fun {bit-ior⎇,Args {@rest @i[bit-vectors]⎇]
@Defun1[Fun {bit-xor⎇, Args {@rest @i[bit-vectors]⎇]
@Defun1[Fun {bit-eqv⎇, Args {@rest @i[bit-vectors]⎇]
@Defun1[Fun {bit-nand⎇, Args {@i[bit-vector1] @i[bit-vector2]⎇]
@Defun1[Fun {bit-nor⎇, Args {@i[bit-vector1] @i[bit-vector2]⎇]
@Defun1[Fun {bit-andc1⎇, Args {@i[bit-vector1] @i[bit-vector2]⎇]
@Defun1[Fun {bit-andc2⎇, Args {@i[bit-vector1] @i[bit-vector2]⎇]
@Defun1[Fun {bit-orc1⎇, Args {@i[bit-vector1] @i[bit-vector2]⎇]
@Defun1[Fun {bit-orc2⎇, Args {@i[bit-vector1] @i[bit-vector2]⎇]
These functions perform bit-wise logical operations on bit-vectors.
All of the arguments to any of these functions must be bit-vectors,
all of the same length.  The result is a bit-vector matching
the argument(s) in length, such that bit @i[j] of the result
is produced by operating on bit @i[j] of each of the arguments.
Indeed, if the arguments are in fact bit-vectors of the same length,
then
@Lisp
(bit-@i[xxx] . @i[arguments]) @EQ (bit-map #'log@i[xxx] . @i[arguments])
@Endlisp
That is, each @f[bit-] function described here is simply a mapping
over bit-vectors of a @f[log] function which applies to integers
(and therefore to the bit values @f[0] and @f[1]).

The following table indicates what the result bit is for each operation
when two arguments are given.  (Those operations which accept an
indefinite number of arguments are commutative and associative,
and require at least one argument.)
@Lisp
@Tabset(+1.5 in, +.3 in, +.3 in, +.3 in, +.3 in)
@Mline()
@>@i[Argument 1]@\0@\0@\1@\1
@ux[@>@i[Argument 2]@\0@\1@\0@\1@\@i[Operation name]]
bit-and@\0@\0@\0@\1@\@r[and]
bit-ior@\0@\1@\1@\1@\@r[inclusive or]
bit-xor@\0@\1@\1@\0@\@r[exclusive or]
bit-eqv@\1@\0@\0@\1@\@r[equivalence (exclusive nor)]
bit-nand@\1@\1@\1@\0@\@r[not-and]
bit-nor@\1@\0@\0@\0@\@r[not-or]
bit-andc1@\0@\1@\0@\0@\@r[and complement of arg1 with arg2]
bit-andc2@\0@\0@\1@\0@\@r[and arg1 with complement of arg2]
bit-orc1@\1@\1@\0@\1@\@r[or complement of arg1 with arg2]
bit-orc2@\1@\0@\1@\1@\@r[or arg1 with complement of arg2]
@Mline()
@Endlisp
@Enddefun

@Defun[Fun {bit-not⎇, Args {@i[bit-vector]⎇]
The argument must be a bit-vector.  A copy of the argument
with all the bits inverted is returned.  That is, bit @i[j]
of the result is @f[1] iff bit @i[j] of the argument is zero.
@Lisp
(bit-not @i[bitvec]) @EQ (bit-map #'lognot @i[bitvec])
@Endlisp
@Enddefun